JavaScript Async Iterator Helper: Scan - Processamento Acumulativo Assíncrono

A programação assíncrona é um pilar do desenvolvimento JavaScript moderno, especialmente ao lidar com operações ligadas a I/O, como requisições de rede ou interações com o sistema de arquivos. Os iteradores assíncronos (async iterators), introduzidos no ES2018, fornecem um mecanismo poderoso para manipular fluxos de dados assíncronos. O helper `scan`, frequentemente encontrado em bibliotecas como RxJS e cada vez mais disponível como um utilitário independente, desbloqueia ainda mais potencial para o processamento desses fluxos de dados assíncronos.

Entendendo os Async Iterators

Antes de mergulhar no `scan`, vamos recapitular o que são os iteradores assíncronos. Um iterador assíncrono é um objeto que está em conformidade com o protocolo de iterador assíncrono. Este protocolo define um método `next()` que retorna uma promessa que resolve para um objeto com duas propriedades: `value` (o próximo valor na sequência) e `done` (um booleano indicando se o iterador terminou). Os iteradores assíncronos são particularmente úteis ao trabalhar com dados que chegam ao longo do tempo ou dados que exigem operações assíncronas para serem buscados.

Aqui está um exemplo básico de um iterador assíncrono:

            
async function* generateNumbers() {
  yield 1;
  yield 2;
  yield 3;
}

async function main() {
  const iterator = generateNumbers();

  let result = await iterator.next();
  console.log(result); // { value: 1, done: false }

  result = await iterator.next();
  console.log(result); // { value: 2, done: false }

  result = await iterator.next();
  console.log(result); // { value: 3, done: false }

  result = await iterator.next();
  console.log(result); // { value: undefined, done: true }
}

main();

            

              
                Copy
              
            
          

Apresentando o Helper `scan`

O helper `scan` (também conhecido como `accumulate` ou `reduce`) transforma um iterador assíncrono aplicando uma função acumuladora a cada valor e emitindo o resultado acumulado. Isso é análogo ao método `reduce` em arrays, mas opera de forma assíncrona e em iteradores.

Em essência, o `scan` recebe um iterador assíncrono, uma função acumuladora e um valor inicial opcional. Para cada valor emitido pelo iterador de origem, a função acumuladora é chamada com o valor acumulado anterior (ou o valor inicial, se for a primeira iteração) e o valor atual do iterador. O resultado da função acumuladora torna-se o próximo valor acumulado, que é então emitido pelo iterador assíncrono resultante.

Sintaxe e Parâmetros

A sintaxe geral para usar o `scan` é a seguinte:

            
async function* scan(sourceIterator, accumulator, initialValue) {
  let accumulatedValue = initialValue;
  for await (const value of sourceIterator) {
    accumulatedValue = accumulator(accumulatedValue, value);
    yield accumulatedValue;
  }
}

            

              
                Copy
              
            
          

• `sourceIterator`: O iterador assíncrono a ser transformado.
• `accumulator`: Uma função que recebe dois argumentos: o valor acumulado anterior e o valor atual do iterador. Ela deve retornar o novo valor acumulado.
• `initialValue` (opcional): O valor inicial para o acumulador. Se não for fornecido, o primeiro valor do iterador de origem será usado como o valor inicial, e a função acumuladora será chamada a partir do segundo valor.

Casos de Uso e Exemplos

O helper `scan` é incrivelmente versátil e pode ser usado em uma ampla gama de cenários envolvendo fluxos de dados assíncronos. Aqui estão alguns exemplos:

1. Calculando um Total Corrente

Imagine que você tem um iterador assíncrono que emite valores de transação. Você pode usar o `scan` para calcular um total corrente dessas transações.

            
async function* generateTransactions() {
  yield 10;
  yield 20;
  yield 30;
}

async function main() {
  const transactions = generateTransactions();
  const runningTotals = scan(transactions, (acc, value) => acc + value, 0);

  for await (const total of runningTotals) {
    console.log(total); // Saída: 10, 30, 60
  }
}

main();

            

              
                Copy
              
            
          

Neste exemplo, a função `accumulator` simplesmente adiciona o valor da transação atual ao total anterior. O `initialValue` de 0 garante que o total corrente comece em zero.

2. Acumulando Dados em um Array

Você pode usar o `scan` para acumular dados de um iterador assíncrono em um array. Isso pode ser útil para coletar dados ao longo do tempo e processá-los em lotes.

            
async function* fetchData() {
  yield { id: 1, name: 'Alice' };
  yield { id: 2, name: 'Bob' };
  yield { id: 3, name: 'Charlie' };
}

async function main() {
  const dataStream = fetchData();
  const accumulatedData = scan(dataStream, (acc, value) => [...acc, value], []);

  for await (const data of accumulatedData) {
    console.log(data); // Saída: [{id: 1, name: 'Alice'}], [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}], [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}]
  }
}

main();

            

              
                Copy
              
            
          

Aqui, a função `accumulator` usa o operador de propagação (`...`) para criar um novo array contendo todos os elementos anteriores e o valor atual. O `initialValue` é um array vazio.

3. Implementando um Limitador de Taxa (Rate Limiter)

Um caso de uso mais complexo é a implementação de um limitador de taxa. Você pode usar o `scan` para rastrear o número de requisições feitas dentro de uma determinada janela de tempo e atrasar as requisições subsequentes se o limite de taxa for excedido.

            
async function* generateRequests() {
  // Simula requisições de entrada
  yield Date.now();
  await new Promise(resolve => setTimeout(resolve, 200));
  yield Date.now();
  await new Promise(resolve => setTimeout(resolve, 100));
  yield Date.now();
}

async function main() {
  const requests = generateRequests();
  const rateLimitWindow = 1000; // 1 segundo
  const maxRequestsPerWindow = 2;

  async function* rateLimitedRequests(source, window, maxRequests) {
    let queue = [];
    for await (const requestTime of source) {
      queue.push(requestTime);
      queue = queue.filter(t => requestTime - t < window);

      if (queue.length > maxRequests) {
        const earliestRequest = queue[0];
        const delay = window - (requestTime - earliestRequest);
        console.log(`Limite de taxa excedido. Atrasando por ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay));
      }
      yield requestTime;
    }
  }

  const limited = rateLimitedRequests(requests, rateLimitWindow, maxRequestsPerWindow);

  for await (const requestTime of limited) {
    console.log(`Requisição processada em ${requestTime}`);
  }
}

main();

            

              
                Copy
              
            
          

Este exemplo usa o `scan` internamente (na função `rateLimitedRequests`) para manter uma fila de timestamps de requisições. Ele verifica se o número de requisições dentro da janela de limite de taxa excede o máximo permitido. Se exceder, ele calcula o atraso necessário e pausa antes de produzir a requisição.

4. Construindo um Agregador de Dados em Tempo Real (Exemplo Global)

Considere uma aplicação financeira global que precisa agregar preços de ações em tempo real de várias bolsas. Um iterador assíncrono poderia transmitir atualizações de preços de bolsas como a Bolsa de Valores de Nova York (NYSE), a Bolsa de Valores de Londres (LSE) e a Bolsa de Valores de Tóquio (TSE). O `scan` pode ser usado para manter uma média móvel ou o preço máximo/mínimo para uma determinada ação em todas as bolsas.

            
// Simula o streaming de preços de ações de diferentes bolsas
async function* generateStockPrices() {
  yield { exchange: 'NYSE', symbol: 'AAPL', price: 170.50 };
  yield { exchange: 'LSE', symbol: 'AAPL', price: 170.75 };
  await new Promise(resolve => setTimeout(resolve, 50));
  yield { exchange: 'TSE', symbol: 'AAPL', price: 170.60 };
}

async function main() {
  const stockPrices = generateStockPrices();

  // Usa o scan para calcular um preço médio corrente
  const runningAverages = scan(
    stockPrices,
    (acc, priceUpdate) => {
      const { total, count } = acc;
      return { total: total + priceUpdate.price, count: count + 1 };
    },
    { total: 0, count: 0 }
  );

  for await (const averageData of runningAverages) {
    const averagePrice = averageData.total / averageData.count;
    console.log(`Preço médio corrente: ${averagePrice.toFixed(2)}`);
  }
}

main();

            

              
                Copy
              
            
          

Neste exemplo, a função `accumulator` calcula o total corrente dos preços e o número de atualizações recebidas. O preço médio final é então calculado a partir desses valores acumulados. Isso fornece uma visão em tempo real do preço da ação em diferentes mercados globais.

5. Analisando o Tráfego de um Site Globalmente

Imagine uma plataforma global de análise da web que recebe fluxos de dados de visitas de sites de servidores localizados em todo o mundo. Cada ponto de dados representa um usuário visitando o site. Usando o `scan`, podemos analisar a tendência de visualizações de página por país em tempo real. Digamos que os dados se pareçam com: `{ country: "US", page: "homepage", timestamp: 1678886400 }`.

            
async function* generateWebsiteVisits() {
  yield { country: 'US', page: 'homepage', timestamp: Date.now() };
  yield { country: 'CA', page: 'product', timestamp: Date.now() };
  yield { country: 'UK', page: 'blog', timestamp: Date.now() };
  yield { country: 'US', page: 'product', timestamp: Date.now() };
}

async function main() {
  const visitStream = generateWebsiteVisits();

  const pageViewCounts = scan(
    visitStream,
    (acc, visit) => {
      const { country } = visit;
      const newAcc = { ...acc };
      newAcc[country] = (newAcc[country] || 0) + 1;
      return newAcc;
    },
    {}
  );

  for await (const counts of pageViewCounts) {
    console.log('Contagem de visualizações de página por país:', counts);
  }
}

main();

            

              
                Copy
              
            
          

Aqui, a função `accumulator` atualiza um contador para cada país. A saída mostraria as contagens acumuladas de visualizações de página para cada país à medida que novos dados de visita chegam.

Benefícios de Usar o `scan`

O helper `scan` oferece várias vantagens ao trabalhar com fluxos de dados assíncronos:

• Estilo Declarativo: O `scan` permite expressar a lógica de processamento acumulativo de forma declarativa e concisa, melhorando a legibilidade e a manutenibilidade do código.
• Manipulação Assíncrona: Ele lida perfeitamente com operações assíncronas dentro da função acumuladora, tornando-o adequado para cenários complexos que envolvem tarefas ligadas a I/O.
• Processamento em Tempo Real: O `scan` permite o processamento em tempo real de fluxos de dados, permitindo que você reaja às mudanças à medida que ocorrem.
• Composibilidade: Pode ser facilmente composto com outros helpers de iteradores assíncronos para criar pipelines complexos de processamento de dados.

Implementando o `scan` (Se Não Estiver Disponível)

Embora algumas bibliotecas forneçam um helper `scan` embutido, você pode facilmente implementar o seu próprio, se necessário. Aqui está uma implementação simples:

            
async function* scan(sourceIterator, accumulator, initialValue) {
  let accumulatedValue = initialValue;
  let first = true;
  for await (const value of sourceIterator) {
    if (first && initialValue === undefined) {
      accumulatedValue = value;
      first = false;
    } else {
      accumulatedValue = accumulator(accumulatedValue, value);
    }
    yield accumulatedValue;
  }
}

            

              
                Copy
              
            
          

Esta implementação itera sobre o iterador de origem e aplica a função acumuladora a cada valor, produzindo o resultado acumulado. Ela lida com o caso em que nenhum `initialValue` é fornecido, usando o primeiro valor do iterador de origem como valor inicial.

Comparação com o `reduce`

É importante distinguir o `scan` do `reduce`. Embora ambos operem em iteradores e usem uma função acumuladora, eles diferem em seu comportamento e saída.

• `scan` emite o valor acumulado para cada iteração, fornecendo um histórico contínuo da acumulação.
• `reduce` emite apenas o valor acumulado final após processar todos os elementos no iterador.

Portanto, o `scan` é adequado para cenários onde você precisa rastrear os estados intermediários da acumulação, enquanto o `reduce` é apropriado quando você precisa apenas do resultado final.

Tratamento de Erros

Ao trabalhar com iteradores assíncronos e o `scan`, é crucial tratar os erros de forma elegante. Erros podem ocorrer durante o processo de iteração ou dentro da função acumuladora. Você pode usar blocos `try...catch` para capturar e tratar esses erros.

            
async function* generatePotentiallyFailingData() {
  yield 1;
  yield 2;
  throw new Error('Algo deu errado!');
  yield 3;
}

async function main() {
  const dataStream = generatePotentiallyFailingData();

  try {
    const accumulatedData = scan(dataStream, (acc, value) => acc + value, 0);

    for await (const data of accumulatedData) {
      console.log(data);
    }
  } catch (error) {
    console.error('Ocorreu um erro:', error);
  }
}

main();

            

              
                Copy
              
            
          

Neste exemplo, o bloco `try...catch` captura o erro lançado pelo iterador `generatePotentiallyFailingData`. Você pode então tratar o erro apropriadamente, como registrá-lo ou tentar a operação novamente.

Conclusão

O helper `scan` é uma ferramenta poderosa para realizar processamento acumulativo assíncrono em iteradores assíncronos de JavaScript. Ele permite que você expresse transformações de dados complexas de maneira declarativa e concisa, lide com operações assíncronas de forma elegante e processe fluxos de dados em tempo real. Ao entender sua funcionalidade e casos de uso, você pode aproveitar o `scan` para construir aplicações assíncronas mais robustas e eficientes. Seja calculando totais correntes, acumulando dados em arrays, implementando limitadores de taxa ou construindo agregadores de dados em tempo real, o `scan` pode simplificar seu código e melhorar seu desempenho geral. Lembre-se de considerar o tratamento de erros e escolher o `scan` em vez do `reduce` quando precisar de acesso aos valores acumulados intermediários durante o processamento de seus fluxos de dados assíncronos. Explorar bibliotecas como RxJS pode aprimorar ainda mais sua compreensão e aplicação prática do `scan` dentro de paradigmas de programação reativa.